#!/usr/bin/python
# -*- coding: utf-8 -*-

#This file is part of pyLot library.
#
# pyLot is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# pyLot is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public License
# along with pyLot.  If not, see <http://www.gnu.org/licenses/>.

__author__ = u'Pierre Puiseux, Guillaume Baty'
__copyright__ = u"Copyright 2011-2012 (C) andheo, Université de Pau et des Pays de l'Adour"
__credits__ = [u'Pierre Puiseux', u'Guillaume Baty']
__license__ = "GNU Lesser General Public License"

__all__ = [u"ICommonRun"]
__date__ = u"9 févr. 2010"
__author__ = u"INRIA pyLot"

from traits.api import Int, Interface, Unicode, Python

class ICommonRun (Interface):
  u"""
  ICommonRun is a class interface representing job execution (job run)
  A run is defined by :
    - a state (NotRunning, Running, Finished)
    - a return code (0: success, else: fail)
  A run can be :
    - killed
    - terminated
    - reset

  You should define classes based on this interface to represent :
    - Python run
    - Shell run
    - Text "run" (actually display would be better)

  A run has also a working_directory attribute. If not set, it uses python
  current working directory. working_directory is type of 
  :class:`~_pylot.minimal.Path`.

  In general such class embeds existing object (like threading.Thread or 
  subprocess.Popen). This object is stored in thread attribute.
  In this case, methods (like kill) just calls corresponding
  methods (self.kill() -> self.thread.kill() [-> Popen.kill()])
  In other case, you must write theses object or methods from scratch
  
  ICommonRun API is inspired by QThread, QProcees (Qt4.QtCore) and
  subprocess.Popen classes.
  """
  # /!\ This code may be useful : http://code.google.com/p/psutil/

  NotRunning = u'NotRunning' # Before start
  Running = u'Running' # Process in progress
  Finished = u'Finished' # Started and neither Paused nor Running
  Paused = u'Paused' # can be continued

  def __init__ (self, thread):
    u"""
    :param thread: run representation object 
    (threading.Thread, subprocess.Popen, PyQt4.QtCore.QProcess, 
    PyQt4.QtCore.QThread, ...)
    :type thread: variable 
    """

  def checkRunningState (self):
    pass

  def terminate (self):
    u"""
    terminate object
    """

  def kill (self, signal=9):
    u"""
    kill object with signal
    """

  def sendline(self, line):
    u"""
    Sends line to current run.
    For example, it may correspond to stdin for a shell run.
    """

  u'execution state: not running, running, finished'
  state = Unicode
  u'execution return code: 0: success, else: fail'
  return_code = Int
  u'execution directory. If not set, use current working directory'
  working_directory = Python


if __name__ == '__main__':
  import doctest
  doctest.testmod()
